---
title: 'Slumber Chunker'
description: 'Agentic chunking powered by generative models via the Genie interface'
icon: 'wand-magic-sparkles'
iconType: 'solid'
---

Meet the `SlumberChunker` – Chonkie's first **agentic chunker**! This isn't your average chunker; it uses the reasoning power of large generative models (LLMs) to understand your text deeply and create truly S-tier chunks.

## API Reference
To use the `SlumberChunker` via the API, check out the [API reference documentation](../../api-reference/slumber-chunker).

## Introducing Genie! 🧞

The magic behind `SlumberChunker` is **Genie**, Chonkie's new interface for integrating generative models and APIs (like Gemini, OpenAI, Anthropic, etc.). Genie allows `SlumberChunker` to intelligently analyze text structure, identify optimal split points, and even summarize or rephrase content for the best possible chunk quality.

<Card
  title="Requires [genie] Install"
  icon="wand-magic"
>
  To unleash the power of SlumberChunker and Genie, you need the `[genie]` optional install. This includes the necessary libraries to connect to various generative model APIs.
</Card>

```bash
pip install "chonkie[genie]"
```

## Installation

As mentioned, SlumberChunker requires the `[genie]` optional install:

```bash
pip install "chonkie[genie]"
```

<Info>For general installation instructions, see the [Installation Guide](/getting-started/installation).</Info>

## Initialization

```python
from chonkie import SlumberChunker
from chonkie.genie import GeminiGenie

# Optional: Initialize Genie
genie = GeminiGenie("gemini-2.5-flash-preview-04-17")

# Basic initialization
chunker = SlumberChunker(
    genie=genie,                        # Genie interface to use
    tokenizer_or_token_counter="character",  # Default tokenizer (or use "gpt2", etc.)
    chunk_size=1024,                    # Maximum chunk size
    candidate_size=128,                 # How many tokens Genie looks at for potential splits
    min_characters_per_chunk=24,        # Minimum number of characters per chunk
    verbose=True                        # See the progress bar for the chunking process
)

# You can also rely on default Genie setup if configured globally
# chunker = SlumberChunker() # Uses default Genie if available
```

## Parameters

<ParamField
    path="genie"
    type="Optional[BaseGenie]"
    default="None"
>
    An instance of a Genie interface (e.g., `GeminiGenie`). If `None`, tries to load a default Genie configuration, which is `GeminiGenie("gemini-2.5-pro-preview-03-25")`
</ParamField>

<ParamField
    path="tokenizer_or_token_counter"
    type="Union[str, Callable, Any]"
    default="character"
>
    Tokenizer or token counting function used for initial splitting and size estimation.
</ParamField>

<ParamField
    path="chunk_size"
    type="int"
    default="1024"
>
    The target maximum number of tokens per chunk. Genie will try to adhere to this.
</ParamField>

<ParamField
    path="rules"
    type="RecursiveRules"
    default="RecursiveRules()"
>
    Initial recursive rules used to generate candidate split points before Genie refines them. See [RecursiveChunker](/chunkers/recursive-chunker#additional-information) for details.
</ParamField>

<ParamField
    path="candidate_size"
    type="int"
    default="128"
>
    The number of tokens around a potential split point that Genie examines to make its decision.
</ParamField>

<ParamField
    path="min_characters_per_chunk"
    type="int"
    default="24"
>
    Minimum number of characters required for a chunk to be considered valid.
</ParamField>


<ParamField
    path="verbose"
    type="bool"
    default="True"
>
    If `True`, prints detailed information about Genie's decision-making process during chunking. Useful for debugging!
</ParamField>

## Usage

### Single Text Chunking

```python
text = """Complex document with interwoven ideas. Section 1 introduces concept A.
Section 2 discusses concept B, but references A frequently.
Section 3 concludes by merging A and B. Traditional chunkers might struggle here."""

# Assuming 'chunker' is initialized as shown above
chunks = chunker.chunk(text)

for chunk in chunks:
    print(f"Chunk text: {chunk.text}")
    print(f"Token count: {chunk.token_count}")
    print(f"Start index: {chunk.start_index}")
    print(f"End index: {chunk.end_index}")
    # SlumberChunk might have additional metadata from Genie
```

### Batch Chunking

```python
texts = [
    "First document requiring nuanced splitting...",
    "Second document where agentic understanding helps..."
]
batch_chunks = chunker.chunk_batch(texts) # Note: Batch processing might be slower due to LLM calls

for doc_chunks in batch_chunks:
    for chunk in doc_chunks:
        print(f"Chunk: {chunk.text}")
```

### Using as a Callable

```python
# Single text
chunks = chunker("Let Genie decide the best way to CHONK this...")

# Multiple texts
batch_chunks = chunker(["Text 1...", "Text 2..."])
```

## Return Type

SlumberChunker returns chunks as `Chunk` objects, potentially with extra metadata attached depending on the configuration and Genie's output.

```python
from dataclasses import dataclass
from typing import Optional

# Definition similar to TokenChunker's return type
@dataclass
class Context:
    text: str
    token_count: int
    start_index: Optional[int] = None
    end_index: Optional[int] = None

@dataclass
class Chunk:
    text: str           # The chunk text
    start_index: int    # Starting position in original text
    end_index: int      # Ending position in original text
    token_count: int    # Number of tokens in chunk
    context: Optional[Context] = None # Contextual information if any
```
